\subsection{Main model}

As you can see the following diagram shows the system's main model. This is between what is stored in the database and what is serialized 
for clients. The Web service is going to work using these classes to handle the client's requests concerning the user, location and note.

  \begin{figure}[ht]
    \centering
    \includegraphics[keepaspectratio, width=1.0\textwidth]{WebService/images/cs_model.png} 
    \caption{Model classes}
    \label{ws-cs_model}
  \end{figure}
  
The \emph{UserInfo} class is the class that holds a user's or administrator's information, which includes the id, nick, name, surname, email, 
phone, country, address, whether it is or is not an administrator and the last known position. The \emph{User} class is used for 
authentication methods where the password of the user is also necessary. This is why this class extends the \emph{UserInfo} class adding a 
field for the password. This class is never serialized and sent through the network.

The \emph{Note} class creates objects to hold information about a note, this means that it contains an id, text, owner's id, position, and photo. 
The photo field can be null if there was no photo attached by the owner. The \emph{Position} class is used to keep information about a GPS 
position and the date and time when it was uploaded. This means that for the Web service a position always has a date and time associated.
The \emph{Photo} class is a simple tool that holds a byte array that represents the picture like it would be stored in the hard disk. The byte 
array could have different format of picture like jpg, what is actually what the android application sends.

The \emph{SUserInfo, SNote, SPosition, SPhoto} classes are just an extension of the previous classes that ensure a correct serialization when 
returned by the Web service. In this section will be explained the interesting options, before the serialization, that these classes offer.



\subsection{Session management}
\label{ws-design.session_management}
The Web service needs some strategy to recognise users between different requests. First strategy would be to ask the user for his 
authentication information, nick and password, each time he calls a method. This has the only advantage of making the solution easier, but has 
the following disadvantages:
\begin{enumerate}
  \item Sending always the authentication information implies more network traffic.
  \item Sending always the authentication information makes easier to sniff and steal this information.
  \item Each time the server gets the information has to check if it is correct in the database.
  \item The server can not tell the difference between two different clients using the same user account.
\end{enumerate}

Because of this reasons is decided to implement a session based authentication system. The basic idea is to create an authentication object for 
each login. This authentication object will be sent to the client so he can keep it and send it for each method he calls. The server keeps the 
list of authentications in the system. Now another problem appears, clients will log into the system lot of times, what means lot of 
authentication objects.
The web service has to decide which authentications are not longer in use and delete them from the list. The server is going to check which 
authentication object has not been used in for a specific time. If this happens the server is going to expire the session, removing the 
authentication object from the list and making it not longer useful for the client. In the diagram the classes used for this part of the 
system are shown:

  \begin{figure}[ht]
    \centering
    \includegraphics[keepaspectratio, width=1.0\textwidth]{WebService/images/cs_auth.png} 
    \caption{Authentication system classes}
    \label{ws-cs_auth}
  \end{figure}
 
The \emph{Auth} class is the authentication object. This object is able to identify a user, and even a session. A user gets a different 
\emph{Auth} object each time he logs in the system. If same user has logged in from two different places is going to have two different 
authentication object, one in each place. In order to get different objects for the same user a session variable is added, that is 
set to a random number when the object is created. The \emph{SAuth} class is the class that extends and ensures the correct serialization 
of the \emph{Auth} class objects.

The \emph{Auths} class checks if the authentication objects are valid. This class extends also Thread (could be done implementing Runnable) 
because it is going to check periodically whether an authentication object has expired. This class keeps the list of authentications in a Map 
so as to be easily found and associated to their \emph{age}. The login process in the web service is shown in the following sequence diagram
\emph{(Figure\ref{ws-login})}:
  \begin{figure}[ht]
    \centering
    \includegraphics[keepaspectratio, width=1\textwidth]{WebService/images/login.png} 
    \caption{\emph{login} sequence diagram}
    \label{ws-login}
  \end{figure}

When the login API is called, it tries to load the user by nick. So the API calls loadUser in the database API with the nick as a parameter. 
Then this \emph{FFLocationDBIface} returns a User object with the user's info, or null if something went wrong, for example if it does not exist.
Now the \emph{Auths} class is going to be called with user's object and password that the client sent. This class checks user's password object 
with the one that was sent by the client. If these two passwords match the authentication class creates an authentication object that is 
registered and returned. When the main process gets the authentication objects, it uses them to create a \emph{SAuth} that is serializable to 
send it to the client. This way, from now on the server will recognise this authentication until it expires.

Let see what happens now that a client tries to create a new administrator account in the next diagram \emph{(Figure\ref{ws-newAdmin})}:
  \begin{figure}[ht]
    \centering
    \includegraphics[keepaspectratio, width=1\textwidth ]{WebService/images/newAdmin.png} 
    \caption{\emph{newAdmin} sequence diagram}
    \label{ws-newAdmin}
  \end{figure}

This method is called with the client's authentication object, the new administrator's \emph{UserInfo} and his new password. The first one 
is very important in this case because it should be associated to an administrator, otherwise it should break. First thing is asking for the  
authentication class which is the owner of the authentication object that was sent. This class checks whether the object is valid, then it 
returns the owner's identification or null if is not valid. After database's interface is asked for the user object that contains the user's 
data of the one with this identification number. If the loaded user is not administrator then it will break because some regular user is 
trying to create an administrator account. Finally the administrator account is created. This is done by creating a User class that extends 
the \emph{UserInfo} class and contains the password field. Once this User class is filled up with the information that the client sent the 
method \emph{newUser} of the database is going to be called. This method returns whether the creation of the account succeeded, what is later 
sent to the client. This way the client knows if the process succeed.

\subsection{Reducing network traffic}
As we could realise in the analysing section the Web service's answer can be really big and most of it not necessary for the client.

\subsubsection{User list request}
Lets say the administrator wants to have a look at the list of users in the system. At some point this list becomes huge and makes it
inefficient(or impossible) to have a function like getting all users. One way to avoid this is asking a parameter that determines what page 
does the client want, lets say that he has pages of five users. Firstly, the user will ask for the first page, which means the first five 
users, and in the second request the next five, and so on. This functionality is a great asset for the user.

But if the client needs to show fifty users each time, he would need ten queries to the web service. This would overload the network too. 
And if you set the pages to fifty, the client that wants less, like the android. It would need to ask too much, to cache them and then 
display them page by page. The solution we have used is based on the \emph{SQL} query's limit parameter. The client will send two parameters, 
first the amount of users that he wantes in each page, and the second one the number of page.

\subsubsection{User's notes request}

After a user has been using the system for a while he probably owns a lot of notes. This number of notes can be too high to be sent to the 
client so it is decided to use a parameter that defines how many notes does the client want. The user's notes are going to be sorted by time, 
and the user will get the most recent n notes. Now that we have limited the number of notes that are returned we consider the fact that these notes 
can be requested just to show them in a map. These notes could be shown without displaying the photo attached, what by the way, is 
the heaviest field in the object.

Finally the method takes as parameters the authentication object, the notes owner's identification number, number notes are requested and 
if you want the photos attached. This last choice is done by the \emph{SNote} class that even if it does not keep the photo it keeps 
in a field if the note has a photo associated, so the client can choose to ask for it later.

\subsection{Getting a note with photo}
In the following sequence diagram is shown how a note is requested to the Web service using the note's identification number 
\emph{(Figure\ref{ws-getNote})}:

  \begin{figure}[ht]
    \centering
    \includegraphics[keepaspectratio, width=1.0\textwidth ]{WebService/images/getNote.png} 
    \caption{\emph{getNote} sequence diagram}
    \label{ws-getNote}
  \end{figure}

Just as it was shown in the previous session management\ref{ws-design.session_management} section the user's identification number is 
obtained by using the authentication object that was sent by the client. Then database is asked for the note with the identification number 
of the note. The database interface returns the note object or null if something went wrong. Now is time to check if the client has rights to 
get that note. When we ask the database if the user with the client's identification number (from the authentication object) and the user who 
owns the note are friends, we should get that they are. This should be the common situation, what makes the following process to be skipped.

If not, the client's user information is loaded from the database. If this client is an administrator then the process continues like they 
where friends, otherwise null is return because the client is not either a friend or an administrator.

At the end of this call to the Web service the note is copied to the \emph{SNote} class with the option that specifies that the photo must 
be copied, because in this method the full note is returned. This means that if the note has a photo associated, it will be attached.


\subsection{Database}

\input{WebService/src/database}

\subsection{Application Programming Interface specification (API)}

Finally the Web service's public methods are shown in the next class diagram, directly connected to the database's interface.

  \begin{figure}[ht]
    \centering
    \includegraphics[keepaspectratio, width=1.0\textwidth]{WebService/images/cs_service.png} 
    \caption{Service's class diagram}
    \label{ws-cs_service}
  \end{figure}


The \emph{exists} function returns true if the nick taken as a parameter is been used, otherwise false. The \emph{login} and \emph{loginWP} 
functions allows clients to login in the system. The only difference between them is that the first one does not allow administrators to log in. 
Both of them need the nick and password so as to match user and get a new valid authentication object, otherwise null is going to be returned.
There is a \emph{newUser} that allows the creation of regular users to anyone. This function takes as parameters the new user's information 
object and the new password. The response is the attempt to log in with this new account, this way it gets logged in just after creating the 
new account.

If a user wants to get his own information he should call \emph{myUser} function that if it takes the right authentication object it will 
return his user information object, otherwise null. To change a user's information the \emph{changeUser} is implemented, that returns whether 
it succeed. It takes as parameters the authentication object that grants rights to do this, the new user information object and the new password.
The \emph{delUser} function is used to delete a user, it has as parameters the authentication object that grants rights and the user to 
delete an identification number. It will return whether it succeeded or not.

When a client makes a friend request he has to use the \emph{askFriend} function and send as parameters the authentication object that 
identifies the user and the request receivers identification number. It returns true if the request was stored, otherwise false. If a user wants 
to know the list of users that had requested him for friendship he must use the \emph{getRequests} function. This function requires just a valid 
authentication object that identifies the user. If something fails, null is returned. The \emph{getFriends} and \emph{getFriendsPage} functions 
allow the client to get his friend list using his authentication object. In the second function the client has to send also the count of users 
he wants and what page he wants. It something goes wrong null is returned.

To send a new client's position, for the history, \emph{logPosition} must be invoked with his authentication object and his position at that 
time. The function will return whether everything worked or not. The \emph{getPositions} methods allow the client to get a user's last n 
positions in an array. The client must send a correct authentication object, the target user's identification number and the number of positions 
he wants at most. If something is not correct null is returned.

When a client wants to create a note in the system he should call \emph{setNote} with the following parameters. The authentication object to 
be recognized by the web service, the position so the note can be located, the note text and the photo if he wants to attach it to the note. 
Notice that the photo is a string because it has to be serialized in a \emph{SOAP} message, but later the serialization issues are explained.
If the client wants to get some other user's notes using \emph{getNotes} he must send the authentication object, the note owner's identification 
number, the maximum amount he wants and whether he wants the photos to be attached. If something goes wrong null is returned, otherwise the 
client gets the user's latest notes in an array. To get a note by identification number the client must send also an authentication object with 
rights to see it and call \emph{getNote}. If the authentication object does not have rights to do so null is returned.

If an administrator wants to see the users of the system he should use the \emph{getUsers} function. This function given a valid administrator's 
authentication object, the count of users per page and the number of page returns the right list of users, otherwise it returns null. If an 
administrator wants to creates another account he can use the \emph{newAdmin} function. This function takes the authentication object of the 
administrator, the new users information object and new password. The response will be if the account was created or not.

Any client with a correct authentication object can search for other users sending also the nick, name, surname and country the results 
should match. Note that the administrators and the users that are friends of the client are removed from the response when a regular user 
calls the method. If something fails this function returns a null value.